Summary

This PR adds a comprehensive runbook documenting the governance admin rotation process for the escrow contract. It explains the complete two-step flow, authorization requirements, timelock behavior, pending state inspection, emitted events, and includes a CLI-style walkthrough to help contributors and operators safely perform admin rotations.

Closes #769

Changes

• Added "docs/escrow/admin-rotation.md" documenting the end-to-end governance admin rotation process.
• Documented the complete rotation lifecycle:
  • Current governance admin calls "propose_governance_admin".
  • Proposal enters a pending state.
  • Wait for "ADMIN_ROTATION_MIN_DELAY_LEDGERS" (approximately two days).
  • Proposed governance admin completes the rotation via "accept_governance_admin".
• Documented authorization requirements for both operations:
  • "propose_governance_admin" requires current governance admin authorization.
  • "accept_governance_admin" requires proposed governance admin authorization.
• Explained the "TimelockNotElapsed" error, including when it is returned and how to resolve it.
• Documented how to inspect pending proposals with "get_pending_governance_admin", including interpretation of the anchor ledger and remaining timelock.
• Included documentation for the emitted:
  • "admin/proposed"
  • "admin/accepted"
    event payloads.
• Added a CLI-style example demonstrating the complete proposal → wait → acceptance workflow.
• Added NatSpec-style ("///") documentation comments in "contracts/escrow/src/governance.rs" linking to the runbook.
• Cross-referenced the timelock tests in "contracts/escrow/src/test/admin_auth_helper.rs".

Security Considerations

• Documents the two-step transfer model to prevent accidental or unauthorized governance changes.
• Clarifies that governance ownership is not transferred immediately after proposal.
• Emphasizes that each stage requires authorization from a different actor.
• Explains the mandatory timelock before ownership can be accepted.

Validation

Verified that the documentation reflects the implementation in "contracts/escrow/src/governance.rs".

Executed:

• ✅ "cargo fmt --all -- --check"
• ✅ "cargo build"
• ✅ "cargo test"